XR

The XR category enables you to work with augmented reality (AR) and virtual reality (VR) content within your applications. The XR category has built-in support for Amazon Sumerian.

Configuration

To download your scene configuration file, visit Amazon Sumerian console, create/open a scene, and select Publish from the top right of the console. Add the following code to your application to configure the XR category:

Amazon Sumerian private scenes do not currently support Unauthenticated access roles when using Amazon Cognito and AWS Amplify Authentication. If you are publishing a private scene, be sure to only include an Authenticated Role/Policy with your Cognito Identity Pool. Learn more about IAM Roles with Cognito Identity Pools.

import { XR } from 'aws-amplify';
import scene1Config from './sumerian-exports'; // This file will be generated by the Sumerian AWS Console 

XR.configure({ // XR category configuration
  SumerianProvider: { // Sumerian specific configuration
    region: 'us-west-2' // Sumerian region
    scenes: { 
      "scene1": { // Friendly scene name
        sceneConfig: scene1Config // Scene configuration from Sumerian publish
      }
    },
  }
});

Or modular import configuration (include only the XR category in your app)

import XR from '@aws-amplify/xr';
import scene1Config from './sumerian-exports'; // This file will be generated by the Sumerian AWS Console 

XR.configure({ // XR category configuration
  SumerianProvider: { // Sumerian specific configuration
    region: 'us-west-2'
    scenes: { 
      "scene1": { // Friendly scene name
        sceneConfig: scene1Config // Scene configuration from Sumerian publish      }
    },
  }
});

Use additional publish parameters

import XR from '@aws-amplify/xr';
import scene1Config from './sumerian-exports'; // This file will be generated by the Sumerian AWS Console 

XR.configure({ // XR category configuration
  SumerianProvider: { // Sumerian specific configuration
    region: 'us-west-2'
    scenes: { 
      "scene1": { // Friendly scene name
        sceneConfig: scene1Config,
        publishParamOverrides: { alpha: true }
      }
    },
  }
});

The XR Category allows a Sumerian scene to be rendered into an DIV HTML element with loadScene method. When the scene is loaded successfully, XR.start() method will start the scene. To render the scene, pass your scene name and the id of the element in the method call:

// Load scene with sceneName: "scene1" into dom element id: "sumarian-scene-dom-id"
async loadAndStartScene() {
    await XR.loadScene("scene1", "sumerian-scene-dom-id");
    XR.start("scene1");
}

// HTML
<div id="sumerian-scene-dom-id"></div>

Scene API

Using optional progress handlers and options

To configure the appearance and the behavior of your Sumerian scene, you can use sceneOptions parameter in the method call:

async loadAndStartScene() {
    const progressCallback = (progress) => {
        console.log(`Sumerian scene load progress: ${progress * 100}%`);
    }

    const sceneOptions = {
        progressCallback
    }
    
    await XR.loadScene("scene1", "sumerian-scene-dom-id", sceneOptions);
    XR.start("scene1");
}

Retrieving the Scene Information

You can check the loading status of the scene with isSceneLoaded method. Also, you can use isMuted method to retrieve audio information about the loaded scene:

if (XR.isSceneLoaded('scene1')) {

    if (XR.isMuted('scene1')) {
        // The scene is muted
        XR.setMuted('scene1', false) // Unmute
    }

}

Entering VR mode

For compatible devices, you can enable VR mode for your scene. When a user enters VR mode with a controller attached, the VR controller component tracks its location in 3D space.

Entering VR requires user input i.e. button press or similar.

if (XR.isSceneLoaded('scene1')) {

    if (XR.isVRCapable('scene1')) {
        XR.enterVR('scene1')
    }

}

Capturing Audio Events

XR Category’s scene controller emits audio-related events during scene playback. You can subscribe to those events with XR.onSceneEvent and provide audio controls in your app, e.g.: providing a volume on button when the browser audio is disabled.

XR.onSceneEvent('scene1', 'AudioEnabled', () => console.log ('Audio is enabled') );
XR.onSceneEvent('scene1', 'AudioDisabled', () => console.log ('Audio is disabled') ));

Enabling Audio

In some browsers, playback of audio is disabled until the user provides input. To reliably enable audio in your scene, wait until the user’s first input, such as a mouse click or screen touch, and then call the enableAudio() method with the scene name.

If the browser is blocking autoplay, the Audio Disabled event will get thrown the first time the scene attempts to PLAY audio, if no user input has been given

XR.enableAudio('scene1')

API Reference

For a complete XR reference visit the API Reference